ODFocusOwnerIterator

Inside Macintosh: OpenDoc Class Reference /: Part 1 - Classes and Methods

ODFocusOwnerIterator

Superclasses
ODObject
Subclasses
none

An object of the ODFocusOwnerIterator class provides access to all owners of a nonexclusive focus.

Description
Foci may be exclusive or nonexclusive. All of the standard foci defined by OpenDoc are exclusive, meaning that only one frame at a time can own a focus. If you create a new kind of focus, you can make it nonexclusive, meaning that several frames could share ownership of it.
You must create a focus-owner iterator if you create a focus module for a nonexclusive focus. The focus module keeps a list of all the individual frames that own the nonexclusive focus. A focus-owner iterator contains a reference to the focus module that manages the nonexclusive focus and provides access to all of the owner frames.
You use a focus-owner iterator to apply an operation to all owners of a nonexclusive focus. For example, a part might use a focus-owner iterator to notify all frames that own a video input focus to synchronize themselves so that the video is displayed in all of the frames simultaneously.
The ODFocusOwnerIterator class is an abstract superclass that you can subclass to create a focus-owner iterator. Your part creates a focus-owner iterator object by calling the arbitrator's CreateOwnerIterator method (page 47). OpenDoc in turn calls the appropriate focus module's CreateOwnerIterator method (page 271), which returns a reference to a focus-owner iterator object.
While you are using a focus-owner iterator, you should not modify the list of focus owners. You must postpone adding frames to or removing frames from the list of focus owners until after you have deleted the iterator.
For more information on accessing objects through iterators, see "Accessing Objects Through Iterators" on page 473 in OpenDoc Programmer's Guide.

Overriding Inherited Methods
The following methods are inherited and available for use by your subclass of ODFocusOwnerIterator.

somInit
The somInit method initializes the instance variables in a SOM object; it is inherited from the SOMObject class.
If you subclass ODFocusOwnerIterator, you can override this method. Your override method does not need to call its inherited method; the inherited method is automatically called for you by the SOM library.
Your override of this method should initialize the new instance variables in this focus-owner iterator object. The SOM library calls this method when this focus-owner iterator is created. You must not do anything that might fail in this method. This limits you to operations like setting pointer variables to null, setting numeric variables to appropriate values, and making similar assignments from constants. If you have any initialization code that can potentially fail, it must be handled in this focus-owner iterator's subclass-specific initialization method; see also the InitFocusOwnerIterator method (page 281).

somUninit
The somUninit method disposes of the storage created for a SOM object; it is inherited from the SOMObject class.
If you subclass ODFocusOwnerIterator, you can override this method. Your override method does not need to call its inherited method; the inherited method is automatically called for you by the SOM library.
Your override of this method should dispose of any storage created for this focus-owner iterator object, including any storage related to additional instance variables initialized in this focus-owner iterator object. The SOM library calls this method when this focus-owner iterator is deleted; this method must not fail.

Methods
This section presents summary descriptions of the ODFocusOwnerIterator methods grouped according to purpose, followed by detailed descriptions in alphabetical order.
Initializing

InitFocusOwnerIterator

Initializes this focus-owner iterator object.
Accessing

First
Should begin the iteration and return a reference to the first frame in the iteration sequence.
Next
Should return a reference to the next frame in the iteration sequence.
Iterator Testing

IsNotComplete
Should return a Boolean value that indicates whether the iteration is incomplete.

Methods
First
InitFocusOwnerIterator
IsNotComplete
Next